Release 10.1A: OpenEdge Development:
Programming Interfaces

Creating and managing unique object identities

It is often helpful, especially for managing user identities, to obtain a value that is guaranteed to be unique. Unique values are useful anywhere you need to reference some object or data that is guaranteed not to conflict with any other of its type. A common use for unique values is to generate unique session identifiers for client-principal objects, so client login sessions can be recorded uniquely, especially for auditing purposes. Another use is to uniquely store exported client-principal objects for later retrieval to set user identities for state-free AppServer sessions (see the "Managing application user IDs in n-tier applications" section).

Progress provides two 4GL functions that work specifically with unique values, as described in Table 2–7.

Table 2–7: Unique value functions 

This 4GL function...	Returns this value...
GENERATE-UUID	A 16-byte RAW value that represents a universally unique identifier (UUID). A UUID is guaranteed to be unique for all practical time and space.
GUID( [ UUID ] )	A CHARACTER value that represents a globally unique identifier (GUID). A GUID is UUID converted to a 36-character string value consisting of 32 hexadecimal digits formatted with 4 hyphens in a standard fashion suitable for display. If you do not specify an argument, the function generates a UUID and returns the GUID for it. If you specify a UUID, which must be 16-byte RAW value, the function converts the UUID argument to a GUID.

When storing unique values to use in database indexes, you need to store them in an efficient character-string format. Progress provides 4GL functions for encoding and decoding RAW (binary) data as character values for use in indexes, or other purposes where you need character storage for such a value. These functions support two different character formats for encoding and decoding RAW data:

Base64
Hexidecimal

Table 2–8 describes these functions.

Table 2–8: Data encoding/decoding functions 

This 4GL function...	Returns this value...
BASE64-ENCODE( expression )	A LONGCHAR value consisting of a Base64 representation of the RAW or MEMPTR value passed as expression.
BASE64-DECODE( expression )	A MEMPTR value that represents the CHARACTER or LONGCHAR value containing a Base64 string passed as expression.
HEX-ENCODE( expression )	A CHARACTER value consisting of a hexadecimal representation (an even number of the digits 0 through 9 and A through F) of the RAW value passed as expression.
HEX-DECODE( expression )	A RAW value that represents the CHARACTER value containing an even number of hexadecimal digits (0 through 9 and A through F) passed as expression.

For character indexes, the BASE64-ENCODE function works especially well with UUID values. You can convert the 16-byte UUID RAW value to a 24-character Base64 string and remove the two trailing pad characters for a final result containing 22 characters:

DEFINE VARIABLE hCP AS HANDLE NO-UNDO. CREATE CLIENT-PRINCIPAL hCP. hCP:SESSION-ID = SUBSTRING(BASE64-ENCODE(GENERATE-UUID), 1, 22).

For examples of other uses for these encoding and decoding functions, see the "Managing and transporting crypto data" section.